Sub-playlists let you control how media groups rotate inside a main playlist. Using Max Items, Max Time, and the Repeat Items option, you can precisely define how long each sub-playlist plays before the player moves on to the next one.
This article walks you through five practical examples, starting from the simplest setup (no limits at all) and building up to more advanced combinations. Each example uses the same data, so you can clearly see how each new setting changes what plays on screen.
Glossary
Max Items: The maximum number of media items the player will show from a sub-playlist before switching to the next one.
Max Time: The maximum total playback time allowed for a sub-playlist before the player switches.
Repeat Items: When enabled, the sub-playlist loops its content from the beginning if it finishes all items before reaching a configured limit.
Playback Rules — Quick Reference
Before jumping into the examples, keep these rules in mind. They apply to every scenario below.
The player evaluates Max Items and Max Time independently. Whichever limit is reached first triggers the switch.
When a limit is reached, the player switches back to the main playlist and moves to the next sub-playlist.
When the player returns to a sub-playlist, it resumes from where it left off and not from the beginning. The only exception is when Repeat Items is enabled, and the sub-playlist finishes all its content without hitting any limit, in which case it starts over.
The player never partially plays a media item. If the remaining allowed time can’t fit the next item in full, that item is skipped entirely.
The Repeat Items option only activates when a sub-playlist finishes all its content before reaching any configured limit.
Quick Cheat Sheet
Use this as a quick reference when deciding how to configure your sub-playlists.
Configuration
Best For
What Happens
No limits
Simple alternation
Each sub-playlist plays all its items, then switches. Every loop is identical.
Max Items only
Controlling item exposure per rotation
Switches after N items, regardless of how long they take.
Max Time only
Equal screen time per group
Switches after the time cap; items that don’t fit the remaining time are skipped.
Max Items + Max Time
Precise control over both count and duration
Whichever limit is reached first triggers the switch.
Repeat Items enabled
Filling a time slot without gaps
Loops content from the beginning until the time limit is reached.
ℹ️ When Repeat Items activates: The sub-playlist finishes all its items → no limit has been reached yet → Repeat Items is ON → playlist restarts. If a limit has already been reached, the Repeat Items is ignored.
Example 1: Two Sub-Playlists, No Limits
The simplest setup. Use this when you want two groups of content to alternate without any time or item constraints, for example, rotating between global marketing content and local announcements. With no limits set, both sub-playlists play all their items in full before switching. Every loop is identical.
Main Playlist Structure
Main Playlist
Sub-Playlist A
No limits · Repeat Items: OFF
Asset 1 — 25″
Asset 2 — 15″
▼
Sub-Playlist B
No limits · Repeat Items: OFF
Asset 1 — 15″
Asset 2 — 20″
Asset 3 — 30″
💡 No limits = no variation. Both sub-playlists play all their items in order. The player switches only once the sub-playlist has finished all its content. Every loop looks exactly the same.
↻ Identical to Loop 1 — this pattern repeats indefinitely
Sub-Playlist A (40″ total)
Sub-Playlist B (65″ total)
Block width ∝ asset duration
Behavior: Each sub-playlist plays all its assets in order from start to finish, then the player moves on. When both sub-playlists have played, the main playlist loop restarts from Sub-Playlist A.
Because there are no limits to trigger an early switch, every loop is identical. If you want variation in what plays per rotation, you need to add Max Items or Max Time — see Examples 2 and 3.
Example 2: Two Sub-Playlists With Max Items Limits
Now we add a Max Items limit to each sub-playlist. This is useful when you want to control exactly how many items from each group play per rotation, for example, show 1 featured promo, then 2 informational slides, then repeat. The player switches as soon as the item count is reached, regardless of how long those items took.
Main Playlist Structure
Main Playlist
Sub-Playlist A
Max Items: 1 · Repeat Items: OFF
Asset 1 — 25″
Asset 2 — 15″
▼
Sub-Playlist B
Max Items: 2 · Repeat Items: OFF
Asset 1 — 15″
Asset 2 — 20″
Asset 3 — 30″
How Max Items works: The player counts items played. As soon as the configured number is reached, it switches — regardless of how long those items took.
Sub-Playlist A plays 1 item per visit.
Sub-Playlist B plays 2 items per visit.
Screen Playback Timeline
Loop 1
Asset 125″# LIMIT (1)
Asset 115″
Asset 220″# LIMIT (2)
0s → 25s25s → 40s40s → 60s
↳ Sub-Playlist A resumes at Asset 2 · Sub-Playlist B resumes at Asset 3
Loop 2
Asset 215″# LIMIT (1)
Asset 330″
Asset 115″# LIMIT (2)
0s → 15s15s → 45s45s → 60s
Sub-Playlist A (max 1 item per visit)
Sub-Playlist B (max 2 items per visit)
Block width ∝ asset duration
Resume-from-position rule: On Loop 2, Sub-Playlist B picks up from Asset 3 (where it left off after Loop 1), then wraps back to Asset 1 to fill its 2-item quota. The player never restarts from Asset 1 — it always continues from the next unplayed item.
All assets get screen time — the sequence just shifts per loop. Sub-Playlist A (2 assets, max 1/visit) and Sub-Playlist B (3 assets, max 2/visit) fully cycle every 2 loops.
Example 3: Two Sub-Playlists With Max Time Limits
Max Time controls how long each sub-playlist plays, not how many items it shows. This example uses a 25-second budget on both sub-playlists. Pay close attention to two things: what happens when the next asset doesn’t fit in the remaining time, and what happens to an asset that’s longer than the limit itself. It will never play.
Main Playlist Structure
Main Playlist
Sub-Playlist A · Max Time = 25″
Max Time: 25s · Repeat Items: OFF
Asset 1 — 25″
Asset 2 — 15″
▼
Sub-Playlist B · Max Time = 25″
Max Time: 25s · Repeat Items: OFF
Asset 1 — 15″
Asset 2 — 20″
Asset 3 — 30″ ⚠
⚠ Permanent skip: Asset 3 in Sub-Playlist B is 30 seconds long. Since the Max Time limit is 25 seconds, it will never fit — no matter when it’s picked. It is permanently skipped in this configuration.
Always ensure your longest asset is shorter than your Max Time setting.
Screen Playback Timeline (Max Time = 25″ per sub-playlist)
↳ Sub-Playlist A resumes at Asset 2 · Sub-Playlist B resumes at Asset 2
Loop 2
Asset 215″
Asset 1 ✕10″ left < 25″
Asset 220″
Asset 3 ✕5″ left < 30″
A2: 15″A1 skippedB2: 20″B3 skipped ⚠
↳ Sub-Playlist A resumes at Asset 1 · Sub-Playlist B resumes at Asset 3 (then falls through to Asset 1)
Loop 3
Asset 125″ · ⏱ limit
Asset 3 ✕always >25″
Asset 115″
Asset 2 ✕10″ < 20″
A1: 25″ → limitB3 perm. skipB1: 15″B2 skip
↻ Pattern from Loop 1 repeats on Loop 3 — the cycle continues
Sub-Playlist A
Sub-Playlist B
Skipped (insufficient time)
Permanently skipped (always > limit)
Skipping rule: The player never plays a media item partially. If the full duration of the next item doesn’t fit within the remaining Max Time window, the item is skipped entirely and the player switches.
B3 (30″) is permanently unreachable because it exceeds the 25″ limit on its own — no matter when it’s picked. It’s not a sequence issue; the asset simply doesn’t fit this configuration. To show it, either increase Max Time to >30″ or shorten the asset.
Example 4: Two Sub-Playlists With Max Items and Max Time Combined
The most advanced limit setup has both Max Items and Max Time active on each sub-playlist, but with different values. The key principle here: whichever limit is reached first triggers the switch. The two limits compete on every visit, and the stricter one always wins. This gives you precise control over both the number of items and the time spent, but it also produces the most varied playback pattern across loops.
Main Playlist Structure
Main Playlist
Sub-Playlist A
Max Items: 2 · Max Time: 25″ · Repeat: OFF
A1 — 25″
A2 — 15″
A3 — 10″
▼
Sub-Playlist B
Max Items: 2 · Max Time: 30″ · Repeat: OFF
B1 — 15″
B2 — 20″
B3 — 30″
Switch Triggers
⏱ TIME Max time limit reached first
# ITEMS Max items limit reached first
⏱ + # Both limits reached simultaneously
Screen Playback Timeline
Loop 1
A125″⏱ TIME
B115″
B2 ✕15″ left < 20″
Loop 2
A215″
A310″⏱+#
B220″
B3 ✕10″ left < 30″
Loop 3
A125″⏱ TIME
B330″⏱ TIME
A1: only item that fits 25″B3: first item picked, fits 30″ exactly — unique to this loop
Loop 4
A215″
A310″⏱+#
B115″
B2 ✕15″ left < 20″
Sub-Playlist A (max 2 items, 25″)
Sub-Playlist B (max 2 items, 30″)
Skipped
B3 (30″) only plays in Loop 3 as first-picked item
Dual-limit behavior: The player evaluates Max Items and Max Time independently — whichever triggers first causes the switch. For Sub-Playlist A in Loops 1 and 3, the 25″ time limit is hit after just 1 item (A1 uses the full budget). In Loops 2 and 4, A plays 2 items (A2 + A3 = 25″) reaching both limits simultaneously.
B3 (30″) can only appear in Loop 3, where it’s the first item picked for Sub-Playlist B and fills the 30″ budget exactly. On all other loops it’s skipped because insufficient time remains when it’s due.
💡Note: Sub-Playlist B’s Max Time here is 30s, not 25s, which is why B3 can fit in Loop 3.
Example 5: Repeat Items Enabled With Max Time Limits
This is where the Repeat Items option comes into play. Use it when a sub-playlist has short assets that need to fill a longer time window without leaving gaps. Instead of switching back early once all items have played, the player loops the content from the beginning and keeps going until the time limit is reached. The result: the full screen time budget is always used.
Main Playlist Structure
Main Playlist
Sub-Playlist A · Max Time = 30″
Max Time: 30″ · Repeat Items: OFF
Asset 1 — 25″
Asset 2 — 15″
▼
Sub-Playlist B · Max Time = 60″
Max Time: 60″ · ↻ Repeat Items: ON
Asset 1 — 5″
Asset 2 — 10″
Asset 3 — 15″
Why Repeat Items matters here:
Sub-Playlist B total content: 5″ + 10″ + 15″ = 30″
Max Time budget: 60″
With Repeat Items ON, the player loops all items from the beginning once the playlist finishes — filling the window: 30″ × 2 passes = 60″ exactly
Without Repeat Items: B plays once (30″) then switches back early, leaving 30″ of screen time unused.
↻ Repeat Items fills the time budget: Sub-Playlist B has 30″ of content but a 60″ budget. Because Repeat Items is ON, the player loops all three items a second time to fill the window exactly. The time limit is what stops it — not the end of content.
Sub-Playlist A alternates per loop: With a 30″ Max Time limit, only one item fits per visit. A1 (25″) plays in Loop 1; A2 (15″) plays in Loop 2. The player resumes from where it left off, so each loop shows a different asset from Sub-Playlist A.
When to use Repeat Items
Use it when your sub-playlist contains short assets (like announcement slides or quick promos) that need to fill a defined time window. Without it, the player would switch back as soon as all items have played once — leaving the rest of the time slot empty.
Repeat Items + Max Items
If both Max Items and Max Time are set, the player counts items across all repeat passes toward the Max Items total. Once Max Items is reached — even mid-repeat — the player switches. Make sure your limits are configured to work together as intended.
Common Misconfigurations
These are the most common ways the player behaves differently from what you might expect. Click each one to see the explanation.
Expecting Repeat Items to always loop content
Repeat Items only activates when a sub-playlist finishes all its items before reaching a configured limit. If a limit (Max Items or Max Time) is reached first, the player switches immediately; therefore, the Repeat Items plays no role.
Expecting a long asset to play even when time is almost up
The player never partially plays a media item. If the next item’s full duration doesn’t fit within the remaining Max Time window, that item is skipped entirely, and the player switches. This prevents partial playback and blank frames, but it also means an asset that’s longer than the Max Time setting will never play in that sub-playlist.
Setting Max Time without accounting for asset durations
If any of your assets are longer than your Max Time setting, they will never play. Always make sure your longest asset is shorter than your Max Time limit. If you want to guarantee a certain number of items always play, use Max Items instead because it’s more predictable when asset durations vary.
Important Playback Notes
Nested sub-playlists
A sub-playlist can contain another sub-playlist. If a parent sub-playlist has Max Items = 1 and contains a nested sub-playlist, the player treats the entire nested sub-playlist as a single item. All the media inside it plays before the parent’s limit is applied.
Timing buffer tip
Small transition delays between media items can accumulate over time, reducing the effective available time within a Max Time window. If you’re using Max Time and need a predictable number of items to always play, add a small buffer to your time setting, roughly 1 extra second for every 5 media items expected to play per visit.
Need Help?
The Yodeck Support Team can help you out! Log in to your Yodeck account and send us a message from the bottom right corner!